package za.org.jcicada.katcp;

/**
 * ISensorValue.java
 *
 * @author Simon Cross
 *
 * Created on October 22, 2008, 17:29
 */

/**
 * Represents a KAT sensor value.
 */
public interface ISensorValue {

    /**
     * Sensor Statuses.
     */
    public enum Status {
        /** Sensor status is not known. */ UNKNOWN,
        /** Sensor is nominal. */ NOMINAL, 
        /** Sensor has experienced a worrying condition. */ WARN,
        /** Sensor has experienced an error. */ ERROR,
        /** Sensor has failed. */ FAILURE;

        /**
         * Return the name of the status value.
         *
         * @return The KATCP name for the sensor Status.
         */
        public String katcpName() {
            return name().toLowerCase();
        }

        /**
         * Find a status for the given name.
         *
         * @param name  The KATCP status name to look up.
         * @return  The Status constant for the given KATCP status name.
         */
        public static Status fromKatcpName(String name) {
            Status status;
            try {
                status = Status.valueOf(Status.class, name.toUpperCase());
            }
            catch (IllegalArgumentException e) {
                throw new IllegalArgumentException(String.format("Unknown sensor status name '%s'", name));
            }
            return status;
        }
    }

    // Interface Methods

    /**
     * Return the value's timestamp in milliseconds.
     *
     * @return  The time at which the sensor value was recorded in milliseconds since the Unix epoch.
     */
    long getTimestamp();

    /**
     * Return the sensor status.
     *
     * @return  The status of the sensor when the value was recorded.
     */
    Status getStatus();

}
